FILE -- A FILE EXAMINER











      FILE allows  rapid examination  of any  word or  range of
      words  in  any disk  file.   It will  display  data  in a
      variety  of  formats.   I  especially  like  the TEMPLATE
      feature.


                                                  Dan Swinehart
                                                6 January, 1971

                                                                   1



                              SECTION I
                            INTRODUCTION

I-A. ________ ____________     Purpose, Capabilities

FILE is an interactive program which allows one to look at any record
of  a disk  file  and examine  its  contents.  In  addition,  it will
provide  auxilliary  information  about  the  file.   A  word  may be
displayed in many different formats; a moderately powerful structure-
display command,  TEMPLATE, is also  available.  A  crude expression-
evaluation facility, the COMPUTE ("←") command is provided,  for what
it's worth.

I-B. _____ _______ ______     Basic Command Format

Most  commands are  of  the form  <verb>  <args>. These  are  used to
specify file names,  display file information,  set write-protection,
compute expressions, read records (one  at a time) into core,  and to
create TEMPLATES (see below).

The basic data-display command requires no verb; it is  recognized by
the presence  of a range  specification (like SOS's),  indicating the
number of words to be shown.  Like SOS, commands exist to display the
next and previous word in a record.

I-C. ________     Examples

These examples will give you the basic flavor of the FILE commands:

FIRST ORTRAN.REL

  would set the file name to ORTRAN.REL and read the first  record of
that file.


12:137

  would type the contents of words 12 (octal) through 137.   The data
mode would be octal unless otherwise specified earlier.


0:10 ASCII

  would display the first 11  (octal) words of the current  record in
ASCII.


INFO

INTRODUCTION                                                       2



  would type out various size and data information about  the current
file.


←57*=128

  would  type  the result  of  the multiplication  (and  save  it for
later).

                                                                   3



                             SECTION II
                        BASIC SYNTACTIC FORMS

II-A. _______      Numbers

A  number  is  an  octal  digit  string  or  a  decimal  digit string
immediately preceded  by the  character "="  (e.g., 345,  =789).  The
character "."  represents the current  word index (determined  by the
last  word  typed  in  the current  record).   If  the  character "\"
immediately precedes a number (e.g. \35, \.), the resulting number is
the  CONTENTS  of the  specified  word in  the  current  record.  The
symbols ;0, ;1, ;2, ... ;9 name ten variables to which values  can be
assigned.   Their  values  are returned  as  numbers  when  these are
mentioned in commands.

II-B. _______ _______      Special Numbers

A Word Number is a number between 0 and =127, inclusive.  It  is used
to refer to words in the current record.

A Record  Number is any  number up  to the size  (in records)  of the
current file.

A Range  Specification is  either a Word  Number, or  a pair  of Word
Numbers  of  the form  Wordno1:Wordno2,  where  Wordno1≤Wordno2.  The
meaning should be clear.

II-C. ____ ______________      File Specifications

A  File Spec  is the  usual  sort of  thing, except  that  the device
portion,  which is  always  assumed to  be DSK:,  is  not recognized.
SAIL-type string constant  quotes can be  used around an  entire file
name (e.g., "$ED$03.TMP") if it would otherwise not look like a legal
symbol (e.g., ORTRAN.REL[1,PDQ] is OK).

II-D. ____ _____      Data Modes

These modes determine  the form of  the output.  Primitive  modes are
OCTAL,  SOCTAL  (signed  octal),  DECIMAL,  ASCII,  SIXBIT,  RADIX50,
FLOATING, DATE, TIME (the latter  two in the standard DEC  format for
times in file retrieval  blocks), BYTE (always followed by  a number,
specifying the byte  size), SEVENS (shorthand  for BYTE 7),  BOTH (of
the form 22(=18)  ), and NULL (not  displayed at all).   More complex
modes (for displaying  repetitive structures where  the substructures
are of different types) may be created from these using  the TEMPLATE
command.

                                                                   4



                             SECTION III
                              COMMANDS

III-A. ___ ____ ____       SET File Spec

This command verifies that  the File Spec represents a  current file,
and prepares to look at it. An error indication is given if something
is wrong.  After any error message, FILE returns to its  main command
loop.

III-B. ____ _____ _____       INFO {File Spec}

This command  displays several lines  of information about  the file.
The braces indicate that  the File Specification may be  omitted ONLY
IF some command  previously has specified a  file.  The same  file is
used.   If a  file  is specified  (here  as with  any  other commands
allowing a file name), a SET File Spec is performed first.

III-C. ______ _______ _______ _____ _____       RECORD <Record Number> {File Spec}

The specified  record (=128 words)  is read into  an in  core buffer.
The  record  number  is  typed back  (in  BOTH  mode)  to  verify the
completion of the input operation.

III-D. _____ _____ _____       FIRST {File Spec}

Equivalent to RECORD 1 {File Spec}

III-E. ____ _____ _____       LAST {File Spec}

Reads the last record of the file.

III-F. ____       NEXT

This command reads the record following the one that is in  core.  If
no file or record has been specified, this is an error.

III-G. ________       PREVIOUS

Guess.

III-H. _____ _____ _____       ALTER {File Spec}

The STORE command is not legal until this command has been  given. It
causes  the file  to be  opened in  ALTER mode,  so  that single-word
changes can be made.

COMMANDS                                                           5



III-I. ________ _____ _____       READONLY {File Spec}

This command makes STORE illegal until another ALTER is issued.

III-J. _____ ________ _____ _______       STORE <Number> [Word Number]

Number is stored in the Word Numberth word of the current record.  If
the Word Number is omitted, the last word displayed is changed.  This
command  is not  allowed until  after an  ALTER has  been  given. The
brackets indicate that no  previous preparation (as with  the braces)
is necessary.

III-K. ___ _______ _______       The Display Command

This command takes the form:

<Range Spec> [Mode [,Mode]* ] [Numbered|Unnumbered]

The asterisk represents the usual "0 or more" repeat, whereas the "|"
represents an (optional) alternative.

The word or  words given by  the Range will  be typed, one  per line.
There will be  a column for  each Mode in the  list.  Each word  in a
column generated  by a simple  Mode will be  displayed in  that Mode.
The words in  columns generated by  Template Modes will  typically be
displayed in  cyclically changing  modes.  This  is much  more easily
demonstrated than explained.

If no  mode at all  appears, the entire  specification from  the last
Display Command  in which  a mode  did appear  is used.   The initial
setting is one column, OCTAL Mode.

Numbered and Unnumbered turn an internal switch on and off.  If it is
on, a word number (0 to =127) is printed as the first column.

III-L. ___ ____ ____ _______       The Next Word Command

Type  <line feed>  to  display the  next  word, using  the  same Mode
setting used in the last Display command.  Nothing will  be displayed
after word =127.

III-M. ___ ________ ____ _______       The Previous Word Command

Type <altmode> to display the previous word.

COMMANDS                                                           6



III-N. ________ ______ ______ _ _ ________       TEMPLATE <Name> <Spec> [ , <Spec>]*

A Spec is either  a Mode (simple or  Template) or a repeat  factor in
parentheses, followed by a Mode. A repeat factor of 1 is  assumed for
any specification lacking one.  This command stores the specification
under the given name.

When a Template is used as a Mode, the first word typed in the column
generated by  the template  will be typed  in the  Mode of  the first
specification in the template  list. Subsequent words in  that column
will  be typed  in the  same Mode  until the  first repeat  factor is
exhausted.  The next  Mode is then used  in a similar manner  for the
words that follow.  When the entire template is exhausted,  the cycle
returns to the first Mode.

If one of the Modes in the Template Specification is a  Template, the
entire  template  is  expanded (as  above)  until  the  repeat factor
preceding  its name  is exhausted,  before moving  on.  You  can nest
these things as deeply as you like.

III-O. _______       Example

TEMPLATE UFD (2) SIXBIT DATE OCTAL

TEMPLATE UFD1 NULL DATE TIME NULL

0:=19 UFD UFD1


This will create output of the form:

 0/ ORTRAN                 (word 0 via UFD in SIXBIT, via UFD1 NULL)
 1/ REL          4-Jan-72  (word 1 via UFD in SIXBIT, via UFD1 DATE)
 2/ 2-Jan-72     1507      (word 2 via UFD as DATE, via UFD1 TIME)
 3/ 776742777777           (word 3 via UFD in OCTAL, via UFD1 NULL)
 4/ PTRAN                  (word 4(0) via UFD in SIXBIT, etc.)

...


These Templates are useful for examining UFD files.  I really haven't
been able to find  a reasonable use for nested  Template definitions,
but they are there if you want them.

COMMANDS                                                           7



III-P. _ ____________       ← <Expression>

An Expression  is a number,  or two numbers  separated by one  of the
operators +, -, *, or /.   The value of the Expression is  typed, and
is  assigned to  one of  the  variables ;0,  ;1, ....  ;9  (in cyclic
order).  You can then refer to these values as Numbers.  Very Crude.

                                                                   8



                             SECTION IV
                            RUNNING FILE

Type "R FILE", wait for the asterisk ("*"), then type  commands until
you have learned what you needed to know (or changed what  you needed
to change).  You can switch files, records, or words at any time.